URLDownload

Downloads data synchronously from a URL into a file, a directory, or memory using a URL reference.

OSStatus URLDownload (
                     URLReference urlRef,
                     FSSpec* destination,
                     Handle destinationHandle,
                     URLOpenFlags openFlags,
                     URLSystemEventProcPtr eventProc,
                     void* userContext);

urlRef

A reference of type URLReference that specifies the URL to be downloaded. Call URLNewReference to create the reference.

destination

A pointer to a structure of type FSSpec that describes the file or directory into which data is to be downloaded, or NULL , in which case you must supply a value for destinationHandle that is a valid handle.

If destination is of type FSSpec , but it does not specify the name of a file or directory, the name of the file or directory specified by the URL is used. If that file or directory already exists and you do not specify kURLReplaceExistingFlag in the openFlags parameter, URLDownload creates a new file or directory whose name has a number appended before the extension. For example, if the URL specifies a file named file.txt , URLDownload changes the filename to file1.txt .

For more information about the FSSpec structure, see Inside Macintosh: Files .

destinationHandle

A handle for downloading data into memory, or NULL , in which case you must specify a value for destination that is a valid file specification. Before calling URLDownload , create a handle of zero size.

openFlags

A value of type URLOpenFlags that specifies download options, such as expanding a file or replacing a file if its filename is already in use. The following constants can be used to specify download options:

kURLReplaceExistingFlag kURLExpandFileFlag kURLDisplayProgressFlag kURLDisplayAuthFlag kURLIsDirectoryHintFlag kURLDoNotTryAnonymousFlag kURLDirectoryListingFlag

See Open Flag Constants for descriptions of these constants.

eventProc

A value of type URLSystemEventProcPtr that points to an application-defined system event callback routine System Event Callback Routine that the URL Access Manager calls to communicate system events to your application during the download process. If your application requests the display of a progress indicator or authentication dialog box, the these items appear in a movable modal dialog box.

The value of eventProc can be NULL , in which case your application will not be informed of system events. If your application requests the display of a progress indicator or authentication dialog box, these items appear in a nonmovable modal dialog box.

userContext

An untyped pointer to arbitrary data that the URL Access Manager passes to the application-defined system event callback routine specified by eventProc . Your application can use userContext to associate a callback with a particular call to URLDownload .

function result

A result code. For a list of possible result codes, see Result Codes .

DISCUSSION

TheURLDownload function downloads data synchronously from a specified URL to a specified file or directory and does not return until the download is complete. The URLDownload function yields time to other threads. Your application should call URLDownload from a thread other than the main thread so that other processes have time to run.

If you want a progress indicator to be displayed during the download, specify kURLDisplayProgressFlag in the openFlags parameter. The URL Access Manager uses a modal dialog box to display the progress indicator. If your application has multiple threads, it can call URLDownload multiple times, but if it calls URLDownload with kURLDisplayProgressFlag set in openFlags when the URL Access Manager is already displaying a modal dialog box, URLDownload returns the error kURLProgessAlreadyDisplayedError .

If the URL reference specifies a file, the file is downloadedregardless of whether kURLDirectoryListingFlag or KURLIsDirectoryHintFlag is set in the openFlags parameter.

When URLDownload downloads data from a file:/// URL, the data fork is downloaded but the resource fork is not downloaded.

WARNING

Once you call URLDownload with urlRef , you cannot use the same urlRef to call URLDownload again, or to call URLUpload or URLOpen . If you need to call URLDownload , URLUpload , or URLOpen with a urlRef that has already been used for one of these calls, you need to create a new URL reference by calling URLNewReference .

Call URLOpen if you need to control the download process.